package za.org.jcicada.comms;

/**
 * ICommsAcceptor.java
 *
 * @author Simon Cross
 *
 * Created on November 24, 2008, 15:52
 */

import java.io.IOException;
import java.net.URI;

/**
 * Interface to a connector acceptor (similar to socket.accept) that creates an
 * IConnection when a client connects.
 * 
 * An IAcceptListener will be attached to an IAcceptor, usually in its
 * constructor. New <em>uninitialized</em> queues should be passed to the
 * IAcceptListener using its .onAccept(queue) method. Should queues die or
 * need to be clean up, the appropriate way to do so is to notify the
 * IAcceptListener using its .onClose(queue) method and allow it to clean
 * up the queue.
 */
public interface IAcceptor {

    /**
     * Shut down the acceptor.
     * 
     * @throws IOException If shutting down the acceptor fails.
     */
    void close() throws IOException;
    
    /**
     * @return true if the acceptor has been closed.
     */
    boolean isClosed();
    
    /**
     * Get the protocol string for location URIs for this acceptor.
     * @return protocol string
     */
    public String getProtocol();

    /**
     * Get access to the base part of a URL for contacting this acceptor
     * containing scheme://authority
     * 
     * @return the base location URI for this acceptor
     */
    public URI getBaseLocationURI();


    /**
     * Access the accept listener.
     * 
     * @return the accept listener
     */
    IAcceptListener getListener();
}
